Using Kubectl Exec: Shell Commands and Examples

Kubernetes is a container orchestrator that lets you automate deployments across multiple physical machines. Starting a shell session to a container in a Kubernetes cluster isn鈥檛 the same as using Secure Shell (SSH) on a physical server. Although containers should be stateless and capable of running without intervention, sometimes you may need a shell to debug issues or extract data.

kubectl exec lets you connect to containers inside your cluster. It鈥檚 part of the full kubectl CLI utility for interacting with Kubernetes installations. The exec command streams a shell session into your terminal, similar to ssh or docker exec.

Here鈥檚 the simplest invocation to get a shell to the demo-pod pod:

kubectl will connect to your cluster, run /bin/sh inside the first container within the demo-pod pod, and forward your terminal鈥檚 input and output streams to the container鈥檚 process. In this article, you will examine the scenarios where kubectl exec is useful, what each section of the command does, and how you can customize the shell connection.

Managing containerized workloads in a Kubernetes cluster requires different processes than those used for applications on a traditional bare-metal server. Because you must drill down from the cluster host to the container instances that deploy your system, there is an extra layer between you and your software.

Kubernetes鈥檚 strength is its ability to distribute replicas across physical machines (nodes). Even if you could use SSH for management, you鈥檇 have to keep track of which node was running each container. kubectl exec lets you specify the container to connect to without worrying about the Kubernetes node it鈥檚 on.

Starting a shell inside a container is most commonly used when you鈥檙e debugging a problem. After exhausting other avenues of inquiry, such as the logs produced by a container, you may have no other option than to inspect it from the inside.

By running the shell commands, you can see the container鈥檚 entire file system and check if the environment is as you expected. It can also help you identify whether a critical file is missing or locked, or find instances of misconfigured environment variables.

Since kubectl exec gives you full shell access, there鈥檚 nothing to stop you from modifying the container, too. This allows you to add extra software packages to aid in your debugging. The extra software packages are sometimes necessary when you are connected to a container that uses a minimal base image where common tools may be missing.

Nonetheless, you should refrain from substantially altering the container鈥檚 environment. Don鈥檛 update existing software packages or use kubectl exec as a way to replace your application鈥檚 source code. These operations would depart from the model of immutability and reproducibility that鈥檚 the foundation of the container movement. Instead, you should rebuild your container image then deploy the new version into your Kubernetes cluster.

To summarize, kubectl exec is a helpful tool when you want to inspect the state of a container in your cluster. It shouldn鈥檛 generally be used to alter the state, except in specific cases where you鈥檙e adding extra debugging packages or fixing a one-off problem in the environment.

Unlike a simple ssh user@server command, kubectl exec requires a few extra arguments to set up an interactive shell session. Let鈥檚 break down the command shown above:

This specifies that you want to run the /bin/sh command in the first container within your demo-pod pod. The -- separates the command to run from the kubectl arguments. Anything after the -- will be passed to the container, as opposed to kubectl.

The -it is equivalent to using the --stdin (-i) and --tty (-t) flags. These instruct kubectl to route your terminal鈥檚 stdin input stream to the container (-i) and treat it as a TTY (-t). This sets up an interactive session where you can supply input to the process inside the container. Without these flags, you鈥檇 see a read-only output stream.

Whereas SSH automatically starts a shell process and binds your terminal鈥檚 input and output streams, kubectl makes each of these aspects customizable. You don鈥檛 have to start a shell in the container; you could run an arbitrary process instead, supply it some interactive input, and receive its output:

Like all other kubectl commands, exec works with the cluster connection defined by your KUBECONFIG environment variable. This should reference a kubeconfig file containing your cluster鈥檚 connection details.

The specified container name must exist within the default cluster namespace. Use the global --namespace flag to change this when you鈥檙e referencing a container in a different namespace:

Containers in a Kubernetes cluster reside within Pods. As each Pod can incorporate several containers, kubectl exec supports an additional argument to let you specify a Pod and container to connect to:

In this example, your connection would be to the demo-container container within the demo-pod pod. In the previous steps, we omitted the container name and only indicated the pod. In this case, kubectl automatically connects to the container with the kubectl.kubernetes.io/default-container annotation or the first container in the Pod when the annotations are not used.

You can also directly reference a higher-level resource, such as a deployment. This reference lets you rapidly connect to a container without needing to know its exact name:

The command above would give you a shell session to the first container within the demo-deployment deployment. It removes the need to run kubectl get pods to discover Pod names before you use exec.

kubectl exec supports a couple of extra options that let you customize its operation:

These arguments should be passed to the kubectl portion of the command before the -- separator that commences the in-container section.

kubectl exec is the best option for getting a shell to a Kubernetes container. It鈥檚 designed specifically for this purpose and circumvents all the issues of identifying the correct physical node to connect to.

If you really need an alternative, perhaps because you must connect from a system without kubectl, you could consider running an SSH daemon inside your container. Beware that this increases your security attack surface and goes against the idea of each container having one single purpose.

Another option is setting up a web-based Kubernetes dashboard. Many popular options, including the official dashboard, are capable of providing interactive shell sessions within your browser.

The kubectl exec command lets you start a shell session inside containers running in your Kubernetes cluster. This command lets you inspect the container鈥檚 file system, check the state of the environment, and perform advanced debugging tools when logs alone don鈥檛 provide enough information.

Manual use of shell commands should be your last resort for managing your containers. Day-to-day monitoring of Kubernetes metrics and critical events is better served by dedicated platforms, such as Datadog, which lets you use prebuilt dashboards to keep tabs on your cluster鈥檚 health.